Embed Authentication

Before the embedding framework is functional, it needs to connect to Pyramid to retrieve the content. This connection needs to be authenticated. Authentication is performed by programmatically logging in as a specific Pyramid user using Pyramid REST security API and saving the authentication token into a local cookie.

You can provide authentication via the Embed Code dialog, simply by selecting the authentication type and inputting the relevant authentication details in the script. You can also provide authentication via the Embed APIs.

NOTE: This code can be called from any technology that supports a RESTful service. However, we recommend that it remain as hidden or compiled code since it involves an authentication processes.

Embed API Authentication

The Embed APIs offer JavaScript enacted authentication - generally only appropriate for modern 'single-page' web applications built with JavaScript, React or Angular. However, the APIs are simply a facade for Pyramid security REST APIs in the end.

Using Virtual Directory deployments

The primary reason to deploy Pyramid as a virtual directory is to allow the authentication into Pyramid to be triggered and resolved in the hosting web application. Once authenticated, the Pyramid security token retrieved by the hosting application is stored in a cookie, which can then be seamlessly used in Pyramid when it is launched in the virtual path. In so doing, the user does NOT need to re-authenticate into Pyramid separately, while still keeping the cookie in the context of the host site's domain.

This approach is often required in various embedding architectures, where the customer wishes to auto-log the user into Pyramid.

Examples

Review the examples below for Java, and raw JavaScript.

  • The URL is the address of your main Pyramid installation.
  • The user provided must be a Pyramid user.
  • The domain is not required unless using Active Directory as your authentication provider in Pyramid
ClosedJava 
BufferedReader in = new BufferedReader(new InputStreamReader(new URL(url + "/API3/auth/embeddedAuth?q={\"data\":{" +
      "\"userName\":\"" + userName + "\"," +
      "\"password\":\"" + password + "\"," +
      "\"domain\":\"" + url.getHost() + "\"}}"
).openStream()));

Cookie cookie = new Cookie("PyramidEmbeddedAuth", in.readLine());
in.close();
response.addCookie(cookie);
ClosedJavaScript

Note: this requires jQuery and the jQuery Cookies library.

Note: authenticating using JavaScript needs to be done carefully if using the quick tags directly from the application. Generally, this will only work with dynamic content embedding.

function GetAuthentication(userName, password) {	
	var credentials = {
		data: {
			userName: userName,
			password: password,
			domain: document.domain
		}
	};

	$.ajax({
		type: "POST",
		url: "https://mysite/API3/auth/authenticateUserEmbed",
		data: JSON.stringify(credentials),
	}).done(function(token) {
		Cookies.set('PyramidEmbeddedAuth',token);	
		// redirect here to the correct page
		location.href = 'embed-page.html';
	});
};